AWS High vs Low level

You can connect to an AWS service by using either high-level or low-level APIs. In general, if the high-level API provides methods you need to perform an operation, use the high-level API because of its simplicity.

For example, when uploading a file to an Amazon S3 bucket, the high-level API uses the file size to determine whether to upload the file in a single operation or upload it in multiple parts. High-level APIs are easier to understand and simpler to use because they provide a higher-level abstraction than low-level APIs.

Low-level API (Service client API in Python)

AWS SDKs provide a set of client classes, each exposing a direct mapping of an AWS service’s API. These client objects have a method for each operation that the service supports, with corresponding objects representing the request parameters and the response data. Using this low-level client API gives you full control over the requests that you make to the service. You can tightly control the behavior and performance of your calls to AWS services.

High-level API (Resource API in Python)

Some AWS SDKs, such as the AWS SDK for Python (Boto3), provide higher-level APIs called the resource APIs. The resource APIs provide a higher-level abstraction than the low-level calls made by clients. The high-level APIs consist of classes that represent each of the conceptual resources that you interact with when using a service. These classes expose methods to do the following:

Retrieve data about the resource
Invoke actions that can be taken on the resource
Retrieve links to other related resources

High-level APIs are easier to understand and simpler to use because they provide a higher-level abstraction and built-in efficiencies than client APIs.

Low-level API - List objects in bucket

Clients return a dictionary so additional API calls needed to get objects. Clients provide a low-level interface to AWS whose methods map close to 1:1 with service APIs. All service operations are supported by clients. Clients are generated from a JSON service definition file.

High-level API - List objects in bucket

Resources represent an object-oriented interface to AWS. They provide a higher-level abstraction than the raw, low-level calls made by service clients.

Client

Clients provide a low-level interface to the AWS service. Their definitions are generated by a JSON service description present in the botocore library. The botocore package is shared between boto3 as well as the AWS CLI.

The service definition for AWS S3 is stored as a JSON under the botocore package.

The main benefit of using the Boto3 client are:

It maps 1:1 with the actual AWS service API. All AWS service operations supported by clients E.g. if you want to list all S3 buckets in your AWS account, you could use the S3 client like this:

import boto3
# Retrieve the list of existing buckets
s3 = boto3.client("s3")
response = s3.list_buckets()

# Output the bucket names
print("Existing buckets:")
for bucket in response['Buckets']:
    print(f'{bucket["Name"]}')

Under the hood, when you create a boto3 client, it uses the botocore package to create a client using the service definition.

Resource

Resources are a higher-level abstraction compared to clients. They are generated from a JSON resource description that is present in the boto library itself. E.g. this is the resource definition for S3.

Resources provide an object-oriented interface for interacting with various AWS services. Resources can be instantiated like the following:

import boto3

s3 = boto3.resource("s3")
Every resource instance is composed of the following:

I dentifiers An identifier is a unique value that is used to uniquely identify a particular resource. Some examples of identifiers are:

# S3 bucket identifier

bucket = s3.Bucket(name="my_bucket")

# S3 object identifier

obj = s3.Object(bucket_name="my_bucket", key="test.py")

Attributes

Resources can also have attributes associated with them. E.g., an S3 object has these attributes associated with it.

Actions

An action is a method which makes a call to the underlying AWS service. An example would be:

obj = s3.Object(bucket_name="my_bucket", key="test.py")

action on S3 Object

response = obj.get()

Clients vs Resources

To summarize, resources are higher-level abstractions of AWS services compared to clients. Resources are the recommended pattern to use boto3 as you don’t have to worry about a lot of the underlying details when interacting with AWS services. As a result, code written with Resources tends to be simpler.

However, Resources aren’t available for all AWS services. In such cases, there is no other choice but to use a Client instead.